@itpay/cli 0.2.4 → 0.2.6

package/README.md

@@ -214,7 +214,7 @@ redacted secure delivery status:
 itp buyer catalog search --query 企业工商 --json
 itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=阿里 --json
 itp buyer checkout create --cart <cart_id> --email <buyer_email> --json
-itp buyer payment wait <payment_intent_id> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --json
 itp buyer checkout status <checkout_id> --json
 ```
 
@@ -239,7 +239,8 @@ Payment QR rules:
 - Otherwise render the ItPay-hosted `qr_png_url` / `preferred_qr_url`.
 - Use `mobile_wallet_url` only as a human mobile fallback.
 - Do not generate your own QR from payment URLs.
-- In agent app clients, send `human_visible_markdown` to the human first, then run `next.command`.
+- In agent app clients, send `human_visible_markdown` or the relevant `render_plan` output to the human first.
+- If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 
 If the human wants the agent to analyze delivered content, the human must reveal

package/bin/itp

@@ -109,7 +109,7 @@ async function main() {
           "buyer checkout status <checkout_id> --json",
           "buyer checkout resume <checkout_id> --json",
           "buyer auth status --json",
-          "buyer payment wait <payment_intent_id> --json",
+          "buyer payment wait <payment_intent_id> --timeout 1 --json",
           "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
           "buyer deliveries list --checkout <checkout_id> --json",
           "buyer deliveries show <delivery_id> --checkout <checkout_id> --json",

package/docs/agent/buyer/cart-checkout.json

@@ -69,7 +69,7 @@
     {
       "intent": "do both steps through the high-level command",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status is waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+      "success_signal": "response.status is waiting_human_auth, payment_handoff_required, payment_verified, or delivery_claimable"
     }
   ],
   "agent_rules": [

package/docs/agent/buyer/payment-qr.json

@@ -18,7 +18,7 @@
     {
       "intent": "create payment intent through the high-level buy flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.human_visible_markdown and response.next.command are present"
+      "success_signal": "response.status is payment_handoff_required; response.human_visible_markdown and response.render_plan are present; render the QR/link to the human before any status check"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,8 +33,10 @@
     "Payment QR display requires both a valid/saved buyer session and payment_intent_id. If payment_intent_id appears before buyer_session is saved, run buyer checkout resume/status instead of showing payment QR.",
     "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
     "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
-    "In Codex or Claude Code app clients, the default UX is show-then-wait: send response.human_visible_markdown to the human first, then run response.next.command.",
-    "For Telegram-style message clients, show response.human_visible_markdown and stop unless the human asks you to keep waiting or returns with a payment question.",
+    "In Codex or Claude Code app clients, send response.human_visible_markdown or response.render_plan.platforms.codex_app.markdown to the human first. Do not start a hidden long wait before the human-visible message is sent.",
+    "For Telegram-style message clients, use response.render_plan.platforms.telegram: send photo media first, include links, and expose native buttons for refresh/status when the adapter supports them.",
+    "For plain chat clients, show response.human_visible_markdown and stop unless the human asks you to check status or returns with a payment question.",
+    "When response.status is payment_handoff_required, response.next is the human reply step, not payment wait.",
     "MUST show local_qr_path first when present. Many agent clients do not reliably render remote QR images; local_qr_path is the most reliable desktop/chat display artifact.",
     "If local_qr_path is not present, show qr_png_url or preferred_qr_url as the primary scannable QR. This is an ItPay-hosted human QR image; it may render the native provider payment code for scanner reliability, but the agent must not request or decode the raw provider payload.",
     "Use qr_image_url/SVG only as a fallback when PNG/local rendering is unavailable.",
@@ -42,8 +44,8 @@
     "payment_entry_url is the stable ItPay status/payment page. qr_png_url/local_qr_path is usually the better desktop scanner artifact.",
     "The provider can briefly show order not found even after precreate succeeded. Tell the human to wait 30-60 seconds and retry the same QR/page. Do not create a new checkout, do not create a new payment intent, and do not repeatedly refresh unless the ItPay page or CLI explicitly asks for recovery.",
     "Opening the payment page must not be treated as paid.",
-    "Do not run payment wait before the QR/link has been sent to the human.",
-    "After showing QR, run next.command or buyer payment wait for the same payment_intent_id."
+    "Do not run payment wait before the QR/link has been sent to the human. Without an explicit short timeout, CLI returns payment_handoff_required instead of blocking.",
+    "After the human says they paid or clicks a platform status button, run response.after_human_response.check_payment_command for the same payment_intent_id."
   ],
   "forbidden": [
     "Do not encode payment_entry_url into a new QR yourself when qr_png_url/local_qr_path is available.",

package/docs/agent/buyer/payment-wait.json

@@ -17,8 +17,8 @@
   "commands": [
     {
       "intent": "wait for payment verified event",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
-      "success_signal": "response.payment_event.event_type == payment_intent.verified"
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "success_signal": "response.payment_event.event_type is payment_intent.verified or wait.timeout"
     },
     {
       "intent": "resume checkout after verified event",
@@ -27,11 +27,12 @@
     }
   ],
   "agent_rules": [
-    "Start payment wait only after the QR image/link has already been sent to the human.",
-    "Payment wait is a recovery loop around the same payment_intent_id, not a one-shot command.",
+    "Start payment status checks only after the QR image/link has already been sent to the human or the human asks to check status.",
+    "If you run payment wait without a short timeout while payment is still pending, CLI returns payment_handoff_required and human_visible_markdown instead of long-polling.",
+    "Payment wait/status check is a recovery loop around the same payment_intent_id, not a one-shot command.",
     "wait.timeout is a heartbeat, not a payment failure.",
-    "In Codex or Claude Code app clients, after showing QR, wait online for a short visible cycle first. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",
-    "Continue waiting with the same payment_intent_id unless the user explicitly cancels or asks you to pause.",
+    "In Codex or Claude Code app clients, after showing QR, use a short status check first. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",
+    "Continue checking the same payment_intent_id unless the user explicitly cancels or asks you to pause.",
     "If the network drops, the process is interrupted, or there is no response, rerun payment wait with the same payment_intent_id or run checkout status/resume with the same checkout_id.",
     "If status is unclear, tell the human it is unclear and continue querying the same payment_intent_id/checkout_id. Do not create a new checkout.",
     "Payment success is payment_intent.verified only.",

package/docs/agent/buyer/qr-refresh.json

@@ -21,7 +21,7 @@
     },
     {
       "intent": "continue waiting after refresh",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
       "success_signal": "payment_event.event_type == payment_intent.verified"
     }
   ],

package/docs/agent/buyer/quickstart.json

@@ -37,7 +37,7 @@
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status becomes waiting_human_auth or waiting_user_payment; if waiting_user_payment, response.human_visible_markdown and response.next.command are present"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if payment_handoff_required, render response.human_visible_markdown or response.render_plan to the human before any payment status check"
     }
   ],
   "agent_rules": [
@@ -54,8 +54,9 @@
     "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
     "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
     "Vault grants are only for reading approved delivered artifacts. They are not buyer session credentials and do not authorize refunds or account/order management.",
-    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown, then run next.command.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown/render_plan, then only check status after the human responds or uses a platform button.",
     "If response.human_visible_markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the human asks to check payment should you run after_human_response.check_payment_command.",
     "Show the returned payment QR exactly as provided before starting payment wait.",
     "Payment truth comes only from payment_intent.verified.",
     "Secure delivery goes to the human first; report redacted delivery status only."

package/docs/agent/buyer/recovery.json

@@ -22,7 +22,7 @@
     },
     {
       "intent": "wait again on the same payment intent",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
     },
     {

package/lib/buyer.js

@@ -4,7 +4,7 @@ import {
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -23,6 +23,7 @@ async function buyerBuy(flags) {
         cart,
         checkout,
         human_action: checkout.human_action,
+        render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
         agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
         next: {
           command: cliCommand("buyer", "checkout", "resume", checkout.checkout_id, "--json"),
@@ -45,18 +46,14 @@ async function buyerBuy(flags) {
 
   if (flags.no_wait || flags.no_wait_payment || showThenWait) {
     output(buyerRunOutput({
-      status: "waiting_user_payment",
+      status: "payment_handoff_required",
       selection,
       cart,
       checkout,
       payment_intent: intent,
-      payment_handoff: paymentHandoff(intent),
-      agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-      next: {
-        command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-        safe_for_agent: true,
-        instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-      }
+      ...paymentHandoffFields(intent, flags),
+      agent_next_actions: paymentHandoffAgentNextActions(),
+      next: paymentHandoffNext()
     }));
     return;
   }
@@ -218,6 +215,9 @@ async function buyer(command, rest, flags) {
           checkout,
           buyer_session: buyerSessionClaimStatus(),
           checkout_guidance: checkoutAuthorizationGuidance(checkout),
+          render_plan: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
+            ? buildHumanActionRenderPlan(checkout.human_action, {}, flags)
+            : undefined,
           agent_next_actions: checkout.agent_next_actions || checkoutAgentNextActions(checkout),
           next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
             ? {
@@ -243,6 +243,9 @@ async function buyer(command, rest, flags) {
         checkout,
         buyer_session: buyerSessionClaimStatus(),
         checkout_guidance: checkoutAuthorizationGuidance(checkout),
+        render_plan: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
+          ? buildHumanActionRenderPlan(checkout.human_action, {}, flags)
+          : undefined,
         agent_next_actions: checkout.agent_next_actions || checkoutAgentNextActions(checkout),
         next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
           ? {
@@ -281,6 +284,7 @@ async function buyer(command, rest, flags) {
             status: "waiting_human_auth",
             checkout,
             human_action: checkout.human_action,
+            render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
             agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
             next: {
               command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
@@ -296,6 +300,7 @@ async function buyer(command, rest, flags) {
             status: "waiting_human_auth",
             checkout,
             human_action: checkout.human_action,
+            render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
             agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
             next: {
               command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
@@ -317,19 +322,15 @@ async function buyer(command, rest, flags) {
           const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
           await renderItPayPaymentAction(intent, flags);
           output(buyerRunOutput({
-            status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
+            status: intent.status === "verified" ? "payment_verified" : "payment_handoff_required",
             checkout,
             payment_intent: intent,
-            payment_handoff: intent.status === "verified" ? undefined : paymentHandoff(intent),
+            ...(intent.status === "verified" ? {} : paymentHandoffFields(intent, flags)),
             buyer_session: buyerSessionClaimStatus(claimedSession),
-            agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"],
+            agent_next_actions: intent.status === "verified" ? (intent.agent_next_actions || checkout.agent_next_actions || ["poll_checkout"]) : paymentHandoffAgentNextActions(),
             next: intent.status === "verified"
               ? { command: cliCommand("buyer", "checkout", "status", checkout.checkout_id, "--json"), safe_for_agent: true }
-              : {
-                command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-                safe_for_agent: true,
-                instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-              }
+              : paymentHandoffNext()
           }));
           return;
         }
@@ -343,16 +344,12 @@ async function buyer(command, rest, flags) {
         const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
         await renderItPayPaymentAction(intent, flags);
         output(buyerRunOutput({
-          status: "waiting_user_payment",
+          status: "payment_handoff_required",
           checkout,
           payment_intent: intent,
-          payment_handoff: paymentHandoff(intent),
-          agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-          next: {
-            command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-            safe_for_agent: true,
-            instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-          }
+          ...paymentHandoffFields(intent, flags),
+          agent_next_actions: paymentHandoffAgentNextActions(),
+          next: paymentHandoffNext()
         }));
         return;
       }
@@ -371,6 +368,18 @@ async function buyer(command, rest, flags) {
     const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
     if (!paymentIntentID) throw new Error("payment_intent_id is required");
     const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
+    if (intent.status !== "verified" && shouldReturnPaymentHandoffBeforeWait(flags)) {
+      await renderItPayPaymentAction(intent, flags);
+      output(buyerRunOutput({
+        status: "payment_handoff_required",
+        payment_intent: intent,
+        ...paymentHandoffFields(intent, flags),
+        payment_guidance: paymentRecoveryGuidance(intent, { event_type: "payment_display_required" }),
+        agent_next_actions: paymentHandoffAgentNextActions(),
+        next: paymentHandoffNext()
+      }));
+      return;
+    }
     const event = intent.status === "verified"
       ? { event_type: "payment_intent.verified", payment_intent_id: paymentIntentID, agent_next_actions: intent.agent_next_actions || ["poll_checkout"] }
       : await waitBuyerPayment(intent, flags);
@@ -382,7 +391,7 @@ async function buyer(command, rest, flags) {
       agent_next_actions: event.agent_next_actions || intent.agent_next_actions || paymentAgentNextActions(intent, event),
       next: event.event_type === "payment_intent.verified"
         ? { command: intent.checkout_id ? cliCommand("buyer", "checkout", "status", intent.checkout_id, "--json") : undefined, safe_for_agent: true }
-        : { command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json"), safe_for_agent: true }
+        : { command: paymentStatusCheckCommand(paymentIntentID), safe_for_agent: true }
     }));
     return;
   }
@@ -392,18 +401,14 @@ async function buyer(command, rest, flags) {
     const refreshed = await refreshBuyerPaymentQR(paymentIntentID, flags);
     await renderItPayPaymentAction(refreshed, flags);
     output(buyerRunOutput({
-      status: refreshed.status === "verified" ? "payment_verified" : "waiting_user_payment",
+      status: refreshed.status === "verified" ? "payment_verified" : "payment_handoff_required",
       payment_intent: refreshed,
-      payment_handoff: refreshed.status === "verified" ? undefined : paymentHandoff(refreshed),
+      ...(refreshed.status === "verified" ? {} : paymentHandoffFields(refreshed, flags)),
       payment_guidance: paymentRecoveryGuidance(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
-      agent_next_actions: refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
+      agent_next_actions: refreshed.status === "verified" ? (refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: "payment_intent.verified" })) : paymentHandoffAgentNextActions(),
       next: refreshed.status === "verified"
         ? { command: cliCommand("buyer", "checkout", "status", refreshed.checkout_id, "--json"), safe_for_agent: true }
-        : {
-          command: paymentWaitCommand(refreshed.payment_intent_id, { short: true }),
-          safe_for_agent: true,
-          instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-        }
+        : paymentHandoffNext()
     }));
     return;
   }
@@ -899,7 +904,7 @@ async function waitBuyerCheckoutAuth(checkout, flags = {}) {
   if (!checkoutID) throw new Error("checkout_id is required");
   const timeoutMs = Number(flags.auth_timeout || flags.timeout || 900) * 1000;
   const started = Date.now();
-  let lastHeartbeatAt = 0;
+  let lastHeartbeatAt = Date.now();
   let current = typeof checkout === "string" ? await getBuyerCheckout(checkoutID, flags) : checkout;
   const authAction = current?.human_action || readCoreAuthAction(checkoutID) || null;
   rememberCoreAuthAction(checkoutID, authAction);
@@ -1036,12 +1041,20 @@ function paymentAgentNextActions(intent = {}, event = {}) {
     return ["poll_checkout_delivery"];
   }
   if (event.event_type === "wait.timeout") {
-    return ["wait_same_payment_intent", "resume_checkout_status_if_needed"];
+    return ["check_same_payment_intent", "resume_checkout_status_if_needed"];
   }
   if (event.event_type === "qr_refreshed") {
-    return ["show_returned_qr", "wait_same_payment_intent"];
+    return ["show_returned_qr", "check_same_payment_intent"];
   }
-  return ["show_payment_qr_if_needed", "wait_same_payment_intent"];
+  return ["show_payment_qr_if_needed", "check_same_payment_intent"];
+}
+
+function paymentHandoffFields(intent = {}, flags = {}) {
+  return {
+    payment_handoff: paymentHandoff(intent),
+    render_plan: buildHumanActionRenderPlan(intent.human_action || {}, intent, flags),
+    after_human_response: paymentHandoffAfterHumanResponse(intent)
+  };
 }
 
 function paymentHandoff(intent = {}) {
@@ -1052,7 +1065,6 @@ function paymentHandoff(intent = {}) {
   const preferredQRURL = action.preferred_qr_url || qrPNGURL || action.qr_image_url || intent.qr_image_url || intent.qr?.image_url || "";
   const localQRPath = action.local_qr_path || intent.local_qr_path || "";
   const mobileWalletURL = action.mobile_wallet_url || intent.mobile_wallet_url || "";
-  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true });
   return {
     type: "payment_qr_handoff",
     payment_intent_id: paymentIntentID || null,
@@ -1064,9 +1076,8 @@ function paymentHandoff(intent = {}) {
     payment_entry_url: entryURL || null,
     mobile_wallet_url: mobileWalletURL || null,
     markdown: paymentHandoffMarkdown({ localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL }),
-    wait_command: waitCommand || null,
     safe_for_agent: true,
-    instruction: "Show markdown to the human first. Then run wait_command and wait for payment_intent.verified unless the human asked you to pause."
+    instruction: "Render the QR/link to the human first. After the human responds or uses a platform button, query the same payment_intent_id. Only payment_intent.verified proves payment."
   };
 }
 
@@ -1076,15 +1087,42 @@ function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRUR
   if (imageURL) lines.push(`![ItPay payment QR](${imageURL})`);
   if (entryURL) lines.push(`[打开付款页面](${entryURL})`);
   if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
-  lines.push("我会继续等待 ItPay 返回 payment_intent.verified。");
+  lines.push("付款后回复“我已付款”，我会查询真实支付状态。");
   return lines.join("\n\n");
 }
 
-function paymentWaitCommand(paymentIntentID, { short = false } = {}) {
+function paymentStatusCheckCommand(paymentIntentID) {
   if (!paymentIntentID) return "";
-  return short
-    ? cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "60", "--json")
-    : cliCommand("buyer", "payment", "wait", paymentIntentID, "--json");
+  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", "--json");
+}
+
+function shouldReturnPaymentHandoffBeforeWait(flags = {}) {
+  if (booleanFlag(flags.wait || flags.long_wait || false)) return false;
+  if (flags.timeout === undefined) return true;
+  const timeout = Number(flags.timeout);
+  return !Number.isFinite(timeout) || timeout > 5;
+}
+
+function paymentHandoffAgentNextActions() {
+  return ["show_human_visible_markdown"];
+}
+
+function paymentHandoffNext() {
+  return {
+    type: "reply_to_human",
+    safe_for_agent: false,
+    instruction: "Send human_visible_markdown to the human now. Do not run payment wait until this message is visible to the human."
+  };
+}
+
+function paymentHandoffAfterHumanResponse(intent = {}) {
+  const paymentIntentID = intent.payment_intent_id || intent.human_action?.id || "";
+  return {
+    check_payment_command: paymentStatusCheckCommand(paymentIntentID),
+    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", "--json") : "",
+    safe_for_agent: true,
+    instruction: "Use check_payment_command after the human says they paid or a platform button requests a status check. User text is not proof; only payment_intent.verified is."
+  };
 }
 
 function paymentRecoveryGuidance(intent = {}, event = {}) {
@@ -1099,10 +1137,10 @@ function paymentRecoveryGuidance(intent = {}, event = {}) {
     next_step: event.event_type === "payment_intent.verified" || intent.status === "verified"
       ? "付款已验证；进入 checkout status / 交付模块。"
       : event.event_type === "wait.timeout"
-        ? "wait.timeout 不是付款失败；继续等待同一个 payment_intent_id，或用 checkout status/resume 确认状态。"
+        ? "wait.timeout 不是付款失败；继续查询同一个 payment_intent_id，或用 checkout status/resume 确认状态。"
         : event.event_type === "qr_refreshed"
-          ? "展示 ItPay 返回的 QR，然后继续等待同一个 payment_intent_id。"
-          : "展示 ItPay 返回的付款入口并等待 payment_intent.verified；用户口头说已付款不算证明。",
+          ? "展示 ItPay 返回的 QR，然后继续查询同一个 payment_intent_id。"
+          : "展示 ItPay 返回的付款入口；用户反馈后查询 payment_intent.verified，用户口头说已付款不算证明。",
     network_or_interrupt: "断网、无响应、进程中断时，重新运行 payment wait 或 checkout status/resume，使用同一个 payment_intent_id / checkout_id。",
     qr_problem: "QR 未显示时不要自造二维码；先用返回的 local_qr_path/qr_png_url/preferred_qr_url。扫码提示订单不存在或过期时，先等 30-60 秒重扫同一 QR，仍失败才 refresh-qr。",
     do_not: [
@@ -1407,12 +1445,13 @@ async function waitBuyerPayment(intent, flags = {}) {
   const waitURL = flags.wait_url || intent?.agent_wait?.wait_url || `/v1/payment-intents/${encodeURIComponent(paymentIntentID)}/events/wait`;
   const timeoutMs = Number(flags.timeout || 900) * 1000;
   const started = Date.now();
-  let lastHeartbeatAt = 0;
+  let lastHeartbeatAt = Date.now();
   let lastEvent = null;
   while (Date.now() - started < timeoutMs) {
+    const remainingMs = Math.max(1000, timeoutMs - (Date.now() - started));
     const params = new URLSearchParams();
     if (cursor) params.set("cursor", cursor);
-    params.set("timeout", String(flags.poll_timeout || "30s"));
+    params.set("timeout", String(flags.poll_timeout || `${Math.ceil(Math.min(30000, remainingMs) / 1000)}s`));
     const event = await coreApi(appendURLQuery(waitURL, params), { method: "GET" }, flags);
     lastEvent = event;
     cursor = event.cursor || cursor;
@@ -1426,10 +1465,10 @@ async function waitBuyerPayment(intent, flags = {}) {
       action: intent?.human_action || null,
       lastHeartbeatAt,
       flags,
-      command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json")
+      command: paymentStatusCheckCommand(paymentIntentID)
     });
   }
-  return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["wait_payment"] };
+  return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["check_payment_status"] };
 }
 
 async function waitBuyerDelivery(checkoutID, flags = {}) {
@@ -1602,6 +1641,7 @@ function compactHumanAction(action = null) {
   if (!action || typeof action !== "object") return action;
   return compactObject({
     kind: action.kind,
+    payment_intent_id: action.payment_intent_id,
     url: action.url,
     local_qr_path: action.local_qr_path,
     local_qr_mime: action.local_qr_mime,
@@ -1651,7 +1691,7 @@ function buyerDocsFor(value = {}) {
     topics.add("cart-checkout");
     topics.add("payment-qr");
   }
-  if (status.includes("waiting_user_payment") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
+  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("show_human_visible_markdown") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
     topics.add("payment-qr");
     topics.add("payment-wait");
   }

package/lib/env.js

@@ -98,10 +98,14 @@ function apiTimeoutMs(flags = {}) {
 }
 
 function parseFlags(args) {
+  const removedQRDisplayFlag = ["--qr", "shown"].join("-");
   const flags = {};
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (!arg.startsWith("--")) continue;
+    if (arg === removedQRDisplayFlag) {
+      throw new Error("legacy QR display flag has been removed; show the payment QR to the human, then run buyer payment wait <payment_intent_id> --timeout 1 --json.");
+    }
     const key = arg.slice(2).replaceAll("-", "_");
     const next = args[i + 1];
     if (!next || next.startsWith("--")) {

package/lib/render-human.js

@@ -7,12 +7,18 @@ import { apiTimeoutMs, cliCommand, commandExists, mergeRun, readRun, readState,
 
 async function renderItPayPaymentAction(intent, flags = {}) {
   const action = intent?.human_action ? { ...intent.human_action } : (intent?.payment_url ? {
+    kind: "payment_qr",
     id: intent.payment_intent_id,
+    payment_intent_id: intent.payment_intent_id,
     title: "Scan payment QR",
     url: intent.payment_url,
     expires_at: intent.qr?.expires_at
   } : null);
   if (action) {
+    if (!action.kind && isPaymentIntentHandoff(intent)) action.kind = "payment_qr";
+    if (!action.id && intent?.payment_intent_id) action.id = intent.payment_intent_id;
+    if (!action.payment_intent_id && intent?.payment_intent_id) action.payment_intent_id = intent.payment_intent_id;
+    if (!action.url && (intent?.payment_url || intent?.payment_entry_url)) action.url = intent.payment_url || intent.payment_entry_url;
     if (intent?.qr_png_url || intent?.qr?.png_url) {
       action.qr_png_url = intent.qr_png_url || intent.qr.png_url;
     }
@@ -35,6 +41,18 @@ async function renderItPayPaymentAction(intent, flags = {}) {
   return result;
 }
 
+function isPaymentIntentHandoff(intent = {}) {
+  return Boolean(
+    intent?.payment_intent_id ||
+    intent?.payment_url ||
+    intent?.payment_entry_url ||
+    intent?.qr_png_url ||
+    intent?.qr_image_url ||
+    intent?.qr?.png_url ||
+    intent?.qr?.image_url
+  );
+}
+
 function humanActionSummaryLines(action) {
   if (!action?.url) return [];
   const lines = [
@@ -265,6 +283,99 @@ function annotateHumanActionPresentation(action, qrImageURL) {
   return action;
 }
 
+function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
+  if (!action || typeof action !== "object") return null;
+  const kind = action.kind || (isPaymentIntentHandoff(intent) ? "payment_qr" : "human_action");
+  const planAction = action.kind === kind ? action : { ...action, kind };
+  const entryURL = intent.payment_entry_url || intent.payment_url || action.url || action.web_url || "";
+  const qrPNGURL = action.qr_png_url || intent.qr_png_url || intent.qr?.png_url || "";
+  const preferredQRURL = action.preferred_qr_url || qrPNGURL || action.qr_image_url || intent.qr_image_url || intent.qr?.image_url || "";
+  const localQRPath = action.local_qr_path || intent.local_qr_path || "";
+  const mobileWalletURL = action.mobile_wallet_url || intent.mobile_wallet_url || humanActionPresentationURL(action, "mobile_wallet_url") || "";
+  const imageSource = localQRPath || qrPNGURL || preferredQRURL;
+  const requiredOutputs = [];
+  if (imageSource) {
+    requiredOutputs.push(compactObject({
+      type: "image",
+      local_path: localQRPath || undefined,
+      fallback_url: preferredQRURL || qrPNGURL || undefined,
+      must_be_user_visible: true
+    }));
+  }
+  if (entryURL) requiredOutputs.push({ type: "link", label: kind === "auth_qr" ? "打开授权页面" : "打开付款页面", url: entryURL });
+  if (mobileWalletURL) requiredOutputs.push({ type: "link", label: "手机钱包打开", url: mobileWalletURL });
+  const markdown = humanActionMarkdown(planAction, { localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL });
+  const telegram = telegramRenderPlan(planAction, { localQRPath, preferredQRURL, entryURL, mobileWalletURL });
+  return compactObject({
+    kind,
+    proof_rule: kind === "payment_qr"
+      ? "Only payment_intent.verified proves payment."
+      : "This human action is not payment proof.",
+    host: agentHost(flags) || undefined,
+    required_outputs: requiredOutputs,
+    platforms: compactObject({
+      codex_app: { format: "markdown_image_and_links", markdown },
+      claude_code: { format: "markdown_image_and_links", markdown },
+      telegram,
+      plain_chat: {
+        format: "image_or_link_then_human_reply",
+        text: kind === "payment_qr"
+          ? "请扫码或点击链接完成支付。付完后回复“我已付款”，我再查询真实状态。"
+          : "请打开上面的授权入口。完成后告诉我，我再继续查询状态。"
+      },
+      terminal: {
+        format: "cli_prints_qr_then_wait",
+        print_terminal_qr: true,
+        print_links: true
+      }
+    }),
+    forbidden: [
+      "Do not say 'scan the QR above' unless an image or scannable URL is actually attached.",
+      "Do not read a local image file as model input and treat that as sent to the human.",
+      "Do not treat page open, QR display, button click, or human text as payment proof.",
+      "Do not create a new checkout because payment is still pending."
+    ]
+  });
+}
+
+function humanActionMarkdown(action = {}, { localQRPath = "", qrPNGURL = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
+  const imageURL = localQRPath || qrPNGURL || preferredQRURL;
+  const lines = [action.kind === "auth_qr" ? "请打开 ItPay 授权入口：" : "请扫码付款："];
+  if (imageURL) lines.push(`![ItPay ${action.kind === "auth_qr" ? "auth" : "payment"} QR](${imageURL})`);
+  if (entryURL) lines.push(`[${action.kind === "auth_qr" ? "打开授权页面" : "打开付款页面"}](${entryURL})`);
+  if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
+  lines.push(action.kind === "payment_qr" ? "付款后回复“我已付款”，我会查询真实支付状态。" : "完成授权后回复，我会继续同一个 checkout。");
+  return lines.join("\n\n");
+}
+
+function telegramRenderPlan(action = {}, { localQRPath = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
+  const media = localQRPath || preferredQRURL
+    ? [compactObject({ type: "photo", local_path: localQRPath || undefined, fallback_url: preferredQRURL || undefined })]
+    : [];
+  const links = [];
+  if (entryURL) links.push({ label: action.kind === "auth_qr" ? "打开授权页面" : "打开付款页面", url: entryURL });
+  if (mobileWalletURL) links.push({ label: "手机钱包打开", url: mobileWalletURL });
+  const buttons = action.kind === "payment_qr"
+    ? [
+      { text: "支付遇到问题 / 刷新", intent: "refresh_payment_qr" },
+      { text: "我已付款，查询状态", intent: "check_payment_status" }
+    ]
+    : entryURL ? [{ text: "打开授权页面", url: entryURL }] : [];
+  return {
+    format: action.kind === "payment_qr" ? "photo_text_inline_buttons" : "text_inline_buttons",
+    media,
+    text: action.kind === "payment_qr"
+      ? "请扫码或点击链接完成支付。付款后点“我已付款，查询状态”。"
+      : "请打开 ItPay 授权入口，完成后回到当前对话。",
+    links,
+    buttons
+  };
+}
+
+function compactObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null && item !== ""));
+}
+
 function shouldPrepareLocalQRForJSON(mode, flags = {}, action = {}) {
   if (mode === "file" || flags.qr_file || process.env.ITP_QR_FILE) return true;
   if (action?.qr_png_url || action?.preferred_qr_url || action?.qr_image_url) return true;
@@ -496,4 +607,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };
+export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -75,7 +75,7 @@ itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity
 itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
 itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json
 itp buyer checkout resume <checkout_id> --json
-itp buyer payment wait <payment_intent_id> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --json
 itp buyer checkout status <checkout_id> --json
 itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --json
 itp buyer refund list --order <order_id> --json
@@ -212,10 +212,14 @@ itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent
 This keeps JSON output machine-readable while allowing the CLI to prepare a
 local QR image path for clients that cannot render remote SVG reliably. In
 Codex or Claude Code app clients, prefer `--no-wait-payment`: send
-`human_visible_markdown` to the human first, then run
-`next.command`. If the human is on mobile, present
-`mobile_wallet_url` as a clickable human-only fallback; do not convert it into a
-QR.
+`human_visible_markdown` or `render_plan.platforms.codex_app.markdown` to the
+human first. If the human is on mobile, present `mobile_wallet_url` as a
+clickable human-only fallback; do not convert it into a QR.
+
+If a response has `status=payment_handoff_required`, `next` is the user-visible
+reply step, not payment wait. Do not run `buyer payment wait` until the human
+has seen the QR/link and asks to check status; then use
+`after_human_response.check_payment_command`.
 
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first